Skip to main content

Request reference

The data catalog API can be called by performing HTTP requests to the AtScale system, and specifying the query details in the body of the requests.

Prerequisites​

To make a request, you need to obtain the following information in advance:

  • Web address of the AtScale system. For details, go to Settings > Organization Settings > Organization in the Design Center.
  • ID of the organization for which requests are performed. You can obtain it by taking the part of the URL that is after /org/ when accessing the Design Center.
  • The data source for which the request is made, and the parameters that should be returned in the response. For details, see the documentation of the data catalog API (catalogs, cubes, dimensions, and so on).

HTTP request​

Each HTTP request you make must use the POST method, must be made to a specific Web address, and must include an authorization header.

The Web address must be as follows:

  • Syntax: http://HOST:10502/xmla/ORGANIZATION
  • HOST is the host name of the AtScale system.
  • ORGANIZATION is the ID of the organization for which you make a request.

The authorization header must be as follows:

  • Syntax: Authorization:Bearer TOKEN
  • TOKEN is the authorization token for the corresponding organization and user account.
  • You can obtain the token with a HTTP GET request to the http://HOST:10500/ORGANIZATION/auth address, by specifying the name and password of the AtScale user account.
  • For example, you can obtain the token withe the curl tool (USER and PWD are the user name and password, respectively):
curl -s -X GET -u USER:PWD "http://atscale-node-01.docker.infra.atscale.com:10500/default/auth"

Optionally, you can also provide the following header: Content-Type: application/xml

Request content​

The data you send in the POST request must be the following SOAP message:

<?xml version="1.0"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <Execute xmlns="urn:schemas-microsoft-com:xml-analysis">
      <Command>
        <Statement></Statement>
      </Command>
    </Execute>
  </Body>
</Envelope>

The <Statement> element in the SOAP message should contain an SQL-like query with the following syntax:

SELECT parameter_list FROM data_source

The parameter_list must be as follows:

  • Located between SELECT and FROM in the query.
  • Containing the data parameters you want to receive in the response. When there are two or more parameters they must be separated with commas.
  • For example, the parameter list for the name and description of a dimension is: DIMENSION_NAME, DESCRIPTION

The data_source must be as follows:

  • Located after FROM in the query
  • Containing the name of the source from which you perform a query.
  • For example, when performing a query for dimensions the source is: $system.MDSCHEMA_DIMENSIONS

Query properties​

The SOAP message (see above) can also contain properties as shown below:

<Properties>
  <PropertyList>
    <Catalog>catalog_name</Catalog>
  </PropertyList>
</Properties>

The properties should be provided as follows:

  • The <Properties> element should be a child of the <Execute> element, before or after the <Command> element.

  • The <Properties> element should have a <PropertyList> child element.

  • The <PropertyList> element should have one or more child elements, where the properties are specified.

    As shown in the example below, using the <Catalog> element you can specify the catalog_name value. This element is often required when making requests.

Request examples​

The documentation for the data catalog API provides many examples for performing requests. Here is an example with the curl tool for requesting the name and last update date of cubes. The token is obtained in advance and provided using the $token variable:

curl -X POST \
-H "Authorization:Bearer $token" -H 'Content-Type: application/xml' \
-d '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">\
<Body>\
<Execute xmlns="urn:schemas-microsoft-com:xml-analysis">\
  <Command>\
    <Statement>SELECT CUBE_NAME, LAST_DATA_UPDATE FROM $system.MDSCHEMA_CUBES</Statement>\
  </Command>\
  <Properties><PropertyList>\
    <Catalog>Sales Insights</Catalog>
  </PropertyList></Properties>\
</Execute></Body></Envelope>' \
http://example.com:10502/xmla/default

More information​

Response reference: How to receive and process responses from the Data Catalog API.